binaryDecode

Type

function

Summary

Decodes binary data and places it into the specified variables.

Syntax

binaryDecode(<formatsList>, <data>, <variablesList>)

Description

Use the binaryDecode function to convert binary data into a form that can be manipulated by handlers.

The binary data format used by binaryDecode is similar to the format produced by the "pack" function of the Perl programming language.

You must declare or otherwise create all variables in the variablesList before using them in the binaryDecode function. Unlike the put command, the binaryDecode function does not automatically create local variables when you use them.

Although the x dataType skips the specified number of bytes rather than converting them, you still must provide a variable for instances of x that appear in the formatsList. The binaryDecode function does not change the value of a variable used for the dataType x.

If the formatsList specifies fewer bytes than are in the data, the binaryDecode function ignores the remaining bytes. If the formatsList specifies more bytes than are in the data, the binaryDecode function converts as many of the dataTypes as there is data for. Check the value that the binaryDecode function returns to determine how much data was actually converted. Here is an example:

    on convertStuff dataToConvert
        global headerData,placeholder,bodyData,footerData
        local convertResult
        put binaryDecode(\"i5x2a24xi2\",dataToConvert, \
              headerData,placeholder,bodyData,placeholder, \ 
              footerData) into convertResult
        if convertResult < 3 then return \"Error: data was corrupted\"
    end convertStuff

Parameters

Name	Type	Description
formatsList		The formatsList consists of one or more dataTypes, each followed optionally by an amount. A dataType is one of the following single letters: x: skip next amount bytes of data a: convert next amount bytes of data to characters A: convert next amount bytes of data (skipping spaces) to characters b: convert next amount bits of data to 1s and 0s B: convert next amount bits of data to 1s and 0s, starting at the high end of each byte h: convert next amount bytes of data to hexadecimal digits H: convert next amount bytes of data to hexadecimal digits, starting at the high end of each byte c: convert next amount bytes of data to signed 1-byte integers C: convert next amount bytes of data to unsigned 1-byte integers s: convert next amount 2-byte chunks of data to signed integers in host byte order S: convert next amount 2-byte chunks of data to unsigned integers in host byte order i: convert next amount 4-byte chunks of data to signed integers in host byte order I: convert next amount 4-byte chunks of data to unsigned integers in host byte order n: convert next amount 2-byte chunks of data to signed integers in network byte order N: convert next amount 4-byte chunks of data to signed integers in network byte order m: convert next amount 2-byte chunks of data to unsigned integers in network byte order M: convert next amount 4-byte chunks of data to unsigned integers in network byte order f: convert next amount 4-byte chunks of data to a single-precision float d: convert next amount 8-byte chunks of data to a double-precision float The amount corresponding to each dataType is an integer or the * character. If no amount is specified, the dataType is used for a single byte of data. The * character causes the rest of the data to be converted according to the formatType, so it should appear only as the last character in the formatsList. Important: If you specify an amount with a string dataType (a or A), the binaryDecode function places amount bytes in the next variable of the variablesList. If you specify an amount with a numeric dataType, the function places amount chunks of data in the next amount variables of the variablesList. For example, the dataType "a3" requires only one variable, which will hold a 3-characterstring, but the dataType "h3" requires three variables, each of which will hold a single hex digit.
data	string	A string of encoded binary data.
variablesList		A comma-separated list of local or global variable names. The number of variable names must be the same as the number of dataTypes specified in the formatsList, and the variables must already exist.

Examples

binaryDecode("h","M",theHex) -- converts M to its hex equivalent

binaryDecode("a*",receivedData,textData) -- converts data to text

binaryDecode("x12Sh16",picHeader,junk,numColors,colorTable)

binaryDecode(myFormat,placeHolder,importantStuff)

Related

command: put

control structure: function

function: numToChar, format, value

glossary: return, binary file, variable, handler, local variable, byte, command

Compatibility and Support

Introduced

LiveCode 1.0

OS

mac

windows

linux

ios

android

Platforms

desktop

server

mobile